Summary

This PR is part of the Comments refactoring (#3227)

This PR implements a multimap for storing the leading, dangling, and trailing comments for nodes.

A naive implementation using three multimaps: one to store the leading, dangling, and trailing parts of each node, requires between nodes < allocations < nodes * 3 vec allocations (nodes = number of nodes with at least one comment).

This purpose-built multimap uses a shared Vec to store all comments where this is possible (99.99% of comments) and only allocates node-specific Vecs for nodes appearing "out of order"

The idea behind the implementation is that comments normally remain in the same order as in the source document. That means:

• All comments for a node are inserted at "the same" time (one at a time, but before inserting the comments of the next node)
• It first inserts the leading, then dangling, and finally, a node's trailing comments.

Using this fact allows storing the vast majority of comments in a single Vec and only storing the offsets into this shared vec indicating the start/end of the leading/dangling/trailing comments. The implementation falls back to allocating (up to) three vectors for a node in case either of the above rules is violated.

Using a single vector for the majority of comments is also beneficial when it comes to iterating because:

• Retrieving the comments for a node requires a single hash map lookup instead of 3
• All comments for a node are located next to each other in the vector, making better use of cache locality.

Metrics

I used countme to verify that the hypothesis that comments appearing out of order are rare by formatting all benchmark files:

cargo run -p xtask_bench --release --features=count  -- --feature=formatter  --criterion=false

rome_formatter::comments::map::InOrderEntry           39_383       34_333            0
rome_formatter::comments::map::OutOfOrderEntry            33           22            0
                                                       total     max_live         live

Out of the close to 40k comments, only 33 nodes required their "own" leading, dangling, and trailing collections. That's 0.0837925%. Or, in other words. This implementation avoids between 40k and 120k vector allocations compared to using three general purpose multimap implementations.

Test Plan

I added a handful of tests to the map implementation